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In last issue's Lab Notes, I explored and 
explained some of the benefits provided by 
Windows' use of the protected mode of the 
Intel 80286, 80386, and 80486 micro- 
processors ("Windows 3.0: All That 
Memory, All Those Modes"). Protected 
mode provides access to megabytes of 
memory, multitasking, and improved sup- 
port for DOS applications. It also greatly 
simplifies memory management for Win- 
dows programmers. Indeed, from a pro- 
gramming viewpoint, Windows 3.0 is a 
protected-mode DOS extender. 

Given Microsoft's market position and 
the rapid acceptance of Windows 3.0, pro- 
tected-mode DOS must be considered the 
dominant operating environment for the 
next few years. 

However, protected mode also has its 

/nside. The Intel protection mechanism 
prevents program bugs from corrupting the 
system, but it also means that your pro- 
grams can't just peek, poke, or call any old 
memory addresses they want. Accessing 
code and data outside your program be- 
comes "impossible." 

But if the vast majority of Windows 
programs are henceforth to be designed to 
run in protected mode, how then will they 
talk to device drivers, TSRs, and other pre- 
cious resources that reside down in the first 
megabyte of memory, in real mode? In a 
nutshell, we must somehow accomplish 
the "impossible." 

This issue's Lab Notes will examine the 
programming challenges software devel- 
opers face as they try to move DOS pro- 
grams to protected-mode Windows. You'll 
see why the keys to the solution lie in the 
new DOS Protected Mode Interface 
(DPMI) and in a number of undocumented 
features of the Windows application pro- 
gram interface (API). 

la PC Magazine's, February 12, 26, and 
March 1 2, 1 99 1 , Power Programming col- 
umns, Ray Duncan showed how non-Win- 
^^ws DOS applications running under 

idows can use DPMI. It is important to 
note that for these DOS programs, DPMI 
is (at least at present) available only in 386 
Enhanced mode. For Windows programs, 



■ Learning to use DPMI 
and a number of 
undocumented Windows 
services is the key to 
accessing real-mode 
memory from protected- 
mode Windows 
programs. 



however, DPMI is available in both Stand- 
ard and Enhanced modes. In this article 
we'll see how and when a Windows appli- 
cation can access DPMI. 

THE PROBLEM WITH PROTECTION 

Because it offers programs a potentially 
enormous address space and because it 
supports multitasking, protected mode 
must establish some "rules of the road" 
that were not necessary in the little 640K 
sandbox of real-mode DOS. These rules 
are the software equivalents of ' 'keep your 
hands to yourself," "don't snoop," and 
"don't chew with your mouth open." 
That is, your programs can't peek (read), 
poke (write), or call (execute) memory that 
isn't mapped into their own address space. 
Furthermore, they can't execute data and 
they can't overwrite code. Protected-mode 
programs can allocate megabytes of mem- 
ory, but they can't access memory that 
isn't theirs. 

But many programs on the PC need 
low-level access to code and data that isn't 
theirs. Key system variables, for example, 
are kept in the BIOS data segment at mem- 
ory location 400h (which can be represent- 



ed by many real-mode addresses, includ- 
ing 0000:0400 and 0040:0000). Needless 
to say, this address is not located inside 
your program. 

You can, of course, try to read this area 
from your protected-mode Windows pro- 
gram, using something like the following 
Ccode: 

unsigned long far *pticks = 

(unsigned long far *) 0x46C; 
unsigned long ticks - *pticks; 

This code works in real mode, but in pro- 
tected mode the variable ticks does not 
end up receiving the BIOS timer-tick 
count. What you get instead is the follow- 
ing message from Windows: 

UNRECOVERABLE APPLICATION ERROR 
Terminating current application. 

Not so good. 

If you run this short program within a 
debugger (CodeView for Windows (CVW) 
or Turbo Debugger for Windows (TDW)), 
your application will not be terminated. In- 
stead, the debugger will display a message 
such as "Trap 13 (0DH) - General Protec- 
tion Fault." If there were some way to re- 
pair the problem while still in the debug- 
ger, you'd be able to resume the program. 
Usually that isn't possible, so there's no 
way to continue past the line of code that 
violated protection. But at least the debug- 
ger shows you where the problem is. 

For a software developer, CVW's 
"General Protection Fault" is a much 
more informative message than Windows' 
"Unrecoverable Application Error" 



JUNE 25, 1991 PC MAGAZINE E2J 



Lab Notes 



REAL-MODE DEV CODE 



COMPLETE LISTII 



i 



ListOfLists far *doslist; 
DeviceDriver far *dd; 
// ... 

dd - 4dosli»t->nul; 

for (;;) 
i 

printf (" %Fp\t" , dd); 

if (dd->attr t CHAR_DEV) 

printf ( "%.8Fs\n", dd->u.name); 

else 

printf ( "Block dev: \u unit(s)\n", dd->u.blk_cnt) ; 
dd - dd->next; 
if (FP_OFF(dd->next) == -1) 

break; 

} 



Figure 2: The C code for walking the DOS device list in real mode. 



(UAE). A general protection fault (GP 
fault) is generated by the Intel processor 
whenever the rules of protected mode have 
been violated. An operating environment 
installs a handler for this INT ODh excep- 
tion. In Windows' case, the handler re- 
sponds by shutting down the offending ap- 
plication and displaying the rather 
uninformative UAE message box. 

Up to this point, we have seen that 
whenever a DOS program that has been 
moved to protected mode tries to access an 
external real-mode memory location such 
as 0040:0000, it generates a GP fault. So 
when you move to protected-mode Win- 
dows, how do you continue to access the 
resources you used in real mode? Besides 
the BIOS data area, for example, how 
would you communicate with a database 
package, TSR, or a network driver? How 
could you access the undocumented DOS 
data structures that PC Magazine utilities 
frequently use? Is there no way to take 
these with you when you cross the border 
into protected mode? 

This is vitally important, for it will be 
many years before every driver, TSR, and 
memory-mapped device is made directly 
accessible in protected mode. Until then, 
developers must be able to access real- 
mode services and absolute memory loca- 
tions from their protected-mode programs. 
Fortunately, as we'll see, the low-level as- 
pects of the machine are still visible from 
protected mode. And programmers who 
can write protected-mode code that talks to 
real mode will find that they have an in- 
creasingly marketable skill. 



WALKING THE DEVICE CHAIN 

Consider a common DOS program that 
simply displays the names and addresses 
of all device drivers loaded on your sys- 
tem. Both Turbo C+ + and Borland C+ + 
come with such a program — called 
TDDEV— and Quarterdeck Office Sys- 
tems' Manifest includes a similar display. 

A DOS program like TDDEV can, of 
course, be run under Windows. But how 
would you turn this into an actual Windows 
program, so that it can interact with the 
user instead of simply dumping informa- 
tion out to the screen? Eventually, you 
might want to make it possible for the user 
to click on a device name to obtain more- 
detailed information. All sorts of possibili- 
ties open up once it's a genuine Windows 
program. But for now let's be content with 
the same, noninteractive output, changing 
the program only so that it runs on the Win- 
dows side of the fence rather than in a DOS 
box. The output of such a Windows DEV 
program is shown in Figure 1 . 

One issue to be faced in contemplating 



the necessary changes is how to structure 
the Windows source code so that it contin- 
ues to resemble, as closely as possible, our 
old character-based DOS code. For exam- 
ple, it would be nice to continue using the 
C printf() function and to avoid (at least for 
the time being) the complexities of Win- 
dows event-driven programming. (This is- 
sue is later explored in the sidebar "Win- 
dows and printf() . ") 

In Windows 3.0, the program will need 
to run in the Standard and 386 Enhanc^ 
modes of Windows. That, in turn, me 
running in the protected mode of the Intel 
80286, 80386, or 80486. A DEV program 
must walk the DOS "device chain, ' ' print- 
ing out the name and address of each driver 
found on this linked list. The challenge in 
porting such a program to protected-mode 
Windows is that the DOS device chain is a 
real-mode data structure, located in con- 
ventional memory. We must somehow ac- 
cess this data structure from protected- 
mode Windows. We have already seen that 
attempting such access normally produces 
a UAE or GP fault. 

It's easy to produce this information in 
a real-mode DOS program. First, you 
make the undocumented DOS call INT 
21h function 52h to get a segmentioffset 
far pointer to the DOS internal variables ta- 
ble (sometimes called the List of Lists). 
The header for the NUL device is stored 
right inside this table, and the NUL device 
is the anchor for the entire DOS device 
chain. It is called a chain because each de- 
vice header contains the address of the next 
device; it is a linked list. 

In Figure 1 , NUL is at the real-mode 
address 0000: 1 228 . It contains a pointer *~ 
the next device, which in this examplt 
SmartDrive (SMART AAR). The pointer 
is simply a 4-byte number, 0000:8B80, the 
address for SMARTAAR. SMART- 
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AAR's device header in turn contains a 
pointer, 0D34:0000, to the Microsoft 
Mouse (MS$MOUSE). The list continues 
in this fashion until it gets to a Lotus/Intel/- 
Microsoft Expanded Memory Manager 
(EMMXXXXO), whose device header 
lives at real-mode address 199F:0000 and 
which, incidentally, has been patched into 
the DOS device chain by Windows in En- 
hanced mode. Here the "next" field con- 
tains a - 1 (FFFFh) in its offset portion. You 
know you've reached the end of the list 
when you find a "next" field whose offset 
isFFFF. 

As the program walks this list, it prints 
out the driver's address, and either the 
name (for character devices) or the number 
of units the device provides (for block de- 
vices). For both cases, this information is 
found in the device header. In a C program 
written for real-mode DOS, a loop that 
walks the device chain would look some- 
thing like the code shown in Figure 2. 

There is a direct correspondence be- 
'"'een this code and the output shown in 

,ure 1. But that display comes from a 
protected-mode Windows program. How 
did the program access these real-mode ad- 
dresses from protected mode? Why didn't 
it terminate with a UAE or a GP fault? 

ENTER DPMI 

As I mentioned earlier, by utilizing the 
DOS Protected Mode Interface (DPMI) 
and some undocumented Windows ser- 
vices, protected-mode Windows programs 
can do all the low-level things they need to 
do, without breaking the rules of protected 



mode. In protected mode, DPMI uses in- 
terrupt 31h to provide a set of services for 
calling real-mode code, mapping real- 
mode memory locations into the protected- 
mode address space, hooking real-mode 
interrupts, and the like. 

Unlike the EMS and XMS specifica- 
tions, DPMI was never designed for wide- 
spread use. It was intended for system soft- 
ware, not application programs. The 
DPMI specification was drawn up by a 
committee that included Microsoft, Intel, 
Lotus, Phar Lap, Quarterdeck, Rational 
Systems, IBM, Borland, and other compa- 
nies, and the assumption was that this 
handful of companies would constitute 
DPMI's user base. 

The true purpose of DPMI is to allow 
the peaceful coexistence of protected- 
mode DOS extenders, expanded memory 
managers, and DOS-based multitasking 
environments. As with the earlier VCPI 
(Virtual Control Program Interface) speci- 



fication developed by Quarterdeck and 
Phar Lap, users — and the vast majority of 
programmers — are expected to care only 
whether the products they use support the 
specification. As for the details of the 
specification itself, they couldn't care less. 

That was the theory. What happened, 
however, is that Windows programmers 
discovered a major gap in the Windows ap- 
plication programmer's interface (API). 
Among all the 500-plus functions listed in 
the massive Windows Programmer' s Ref- 
erence there is nothing that lets you call a 
DOS device driver, for example. You 
can't even find its location in memory. 

DPMI, on the other hand, does provide 
services that allow low-level access to the 
machine from protected mode. And DPMI 
is incorporated in Windows. Consequent- 
ly, many programmers look to DPMI (and 
to a number of useful, but undocumented 
Windows functions and features) as the 
back door to Windows 3 .0 (to coin a mixed 
metaphor). 

CALLING DPMI 

Before jumping in and applying DPMI di- 
rectly to our DEV program, let's sample a 
more easily digested example of DPMI in 
a Windows program. DPMIINFO is a 
small utility that simply displays a few in- 
teresting facts about whatever DPMI im- 
plementation is present. The screenshots 
of DPMIINFO shown in Figures 3 and 4 
summarize some of the crucial differences 
between Windows Standard and 386 En- 
hanced modes. While these were dis- 
cussed in last issue's Lab Notes, they're 
worth reviewing here. 

Whereas 386 Enhanced mode supports 
virtual memory (paging to disk) and is 
386-based (that is, it supports 32-bit pro- 
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tected-mode DOS and Windows pro- 
grams), Standard mode is 286-based (it 
supports only 16-bit programs) and does 
not provide virtual memory. Furthermore, 
in 386 Enhanced mode, interrupts generat- 
ed in protected mode (such as interrupt 
21h) are "reflected" (passed on) to DOS 
running in Virtual 86 (V86) mode, while 
in Standard mode, DOS is running in 
plain-old real mode. 

The lines "Windows Standard mode 
running on an 80386" and "286-based 
DPMI implementation" in Figure 3 also 
remind you that the 286-based 16-bit-only 
Standard mode can just as easily run on an 
80386 processor as on an actual 80286. 

Finally, Figures 3 and 4 also indicate 
that Windows 3.0 uses DPMI, Version 
0.9. While the specifications for DPMI 1 .0 
have been drawn up, it's DPMI 0.9 that 
most end users will have on their machines 
for some time to come. (The DPMI 0.9 
specification is available free of charge 
from Intel. Call 1-800-548-4725 and ask 
for Part No. 240763.) 

Turning to the DPMHNFO.C source 
code, which is shown in Figure 5, we see 
that there are several tests that should be 
made before you call the DPMI INT 31h 
functions. 

First, you should see whether you are 
running in protected mode. We use the 
Windows API GetWinFlags() function for 
this. 



Next, you check whether DPMI is pre- 
sent, using the DPMI Mode Detection 
call, INT 2Fh AX= 1686h. (Note that this 
is not the INT 2Fh AX= 1687h call, which 
is used to obtain the real-to-protected 
mode switch entry point, and which was 
discussed in last issue's Lab Notes and in 
Ray Duncan's columns on DPMI. The 
2F/1687 call is to be made by a real-mode 
program that wants to use DPMI to switch 
into protected mode; a program calls 
2F/1686 to see whether it is already run- 
ning in protected mode under DPMI.) 

Windows applications are loaded in 
protected mode automatically, so they 
don't need the 2F/1686 call. This is fortu- 
nate, as this call is not currently supported 
in Windows Standard mode. That is pre- 
cisely why DOS programs running in 
Standard mode can't access DPMI but 
Windows programs can. 

Once you have determined that you are 
running in protected mode under DPMI, 
you can make interrupt 31h calls: INT 31h 
services are provided in protected mode 
only. In Figure 5, then, we call the DPMI 
Get Version function (INT 3 lh 
AX=0400h). The functions dpmi_pre- 
sent() and dpmi_version() called by 
DPMHNFO.C in Figure 5 are both provid- 
ed (along with many other DPMI-related 
functions) by DPMI.H and DPMI.C, 
whose code listings are shown in Figures 6 
and 7 respectively. 

Note that DPMI.C (in Figure 7) uses in- 
line assembly language to make INT 2Fh 
and INT 31h calls. Microsoft C 6.0 and 
Borland C++ 2.0 both provide an in-line 



assembler, and DPMI.C will work with 
either compiler. We avoid the C int8^ 
and int86x() functions here, because man_y 
implementations of these functions cause 
GP faults in protected mode — which is 
precisely what we're trying to avoid by go- 
ing to DPMI! 

In addition to the functions in DPMI.C 
and DPMI.H, you may want to look into 
one of several DPMI libraries now being 
sold. For example, Soft Works Internation- 
al (404-876-6115) sells a library called 
SoflDPMI. 

CALLING REAL-MODE SERVICES 

We are now in a position to see how DPMI 
helps move the DEV program to Win- 
dows. In DEV.C (Figure 8), several 
blocks of code have been marked 

lifdef WINDOWS 

This code is used when you build a pro- 
gram with -DWINDOWS on the compiler 
command line. 

The first such block appears in the func- 
tion get_doslist(). This is the function that, 
as noted earlier, calls the undocumented 
DOS function INT 21h AH=52h and re- 
turns a far pointer to the DOS internal v; 
ables table. 

When it is being compiled for Win- 
dows, get_doslist() calls the function 
dpmi_rmode_intr(), which is declared in 
DPMI.H (Figure 6) and implemented in 
DPMI.C (Figure 7). The dpmi_rmode_ 
intr() function simply provides a C inter- 
face to the DPMI Simulate Real Mode In- 
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DPMHNFO.C — display DPMI information under Windows 

Copyright (c) 1991 ziff Communications Co. 
PC Magazine * Andrew Schulman 

Borland C++ 2.0: 

bcc -w -2 dpmiinfo.c printf.c dpmi.c 
rc dpmiinfo.exe 

Microsoft C 6.0: 

cl -c -AS -G2sw -oais -zpe dpmiinfo.c printf.c dpmi.c 

link /align:16 dpmiinfo printf dpmi , dpmiinf o, , /nod siibcew libw,wij 

rc dpmiinfo.exe 



(include -iBtdlib.h> 
linclude <stdarg.h> 
linclude <stnng.h> 
(include <dos.h> 
linclude <wmdows.h> 
(include "printf. h" 
linclude "dpmi.h" 

(define FAIL(s) Mess age Box ( NULL, s, "DPMI Information", MB 

int PASCAL winMain ( HANDLE hlnstance, HANDLE hPrevInstance, 
LPSTR IpszCmdLine , int ncmdshow) 

{ 

unsigned long win_flags; 
unsigned flags; 
unsigned maj, min; 



unsigned proc; 

if ( I ((win_flags = GetWinFlags ( ) ) & WF_PMOl>E}) 
return FA I L ( " Th i s program requires windows " 
"Standard or Enhanced mode"); 

if < '. dpmi_present ( ) } 

return FAIL ( "DPMI not present"); 

dpmi_version ( &ma j , Smin, if lags, iproc ) ; 

open^display ( "DPMI Information" ) ; 

if |win_flags £ WF_STANDARD) 

pr intf ( "DPMI %x , %x\n" , ma j , i 

else 

printf (-DPMI %d.%d\n", maj, i 

prmtf ( "Windows %s mode running on an 88%d86\n", 
(win_ flags t, WF_ENHANCED> ? "Enhanced- : 

(wm_flags & WF_STANDARD) ? "Standard" : "Not Another?!" 

procT; // processor: 2=286, 3"386, 4=486 
printf ("td-based DPMI implementation'^" , 

(flags & 1 ) ? 386 : 286) j 
printf ( "Interrupts reflected to %s mode\n", 

(flags 4 2)? "real" : "V86"); 
printf("%s virtual memory\n", 

(flags *4)? "Supports" : "No"); 

show_display ( ) ; 
return 0; 



in>; // silly bug in standard mode 
in)! 



Figure 5: The DPMIINFO program displays the DPMI information shown in Figures 3 and 4. 
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/* DPMI.H */ 

#pragma pack(l) 

typedef struct { 

unsigned long edi, esi, ebp, reserved, ebx, edx, ecx, eax; 
unsigned flags, es, ds, fs, gs, ip, cs, sp, ss; 
} RMODE_CALL; 

/* structure of a protected-mode descriptor */ 
typedef struct { 

unsigned limit, addr lo; 

unsigned char addr_hT, access, reserved, addr_xhi; 
} DESCRIPTOR; 

/* low-level DPMI functions */ 
BOOL dpmi_present ( void ) ; 

void dpmi_version(unsigned *pmaj, unsigned *pmin, 

unsigned *pflags, unsigned *pproc); 
BOOL dpmi_rmode_intr( unsigned intno, unsigned flags, 

unsigned cop/words, RMODE_CALL far *rmode_call ) ; 
unsigned dpmi_sel(void) ; 

BOOL dpmi_set_descriptor(unsigned pmodesel, DESCRIPTOR far *d); 
BOOL dpmi_get_descriptor(unsigned pmodesel, DESCRIPTOR far *d); 
BOOL dpmi_sel_f ree(unsigned pmodesel); 

/* higher layer on top of DPMI */ 

unsigned DosAllocRealSeg(DWORI> bytes, unsigned *ppara, unsigned *psel); 
unsigned DosFreeRealSeg(unsigned sel); 

unsigned DosMapRealSeg ( unsigned rmpara, DWORD size, unsigned far *psel); 

unsigned DosFreeSegfunsigned sel); 

void far "DosProtToReal ( void far *prot); 

void far "map_real(void far *rptr, unsigned long size); 
void f ree_mapped_seg( void far *fp); 
■nsigned get_mapped(void) ; 
nsigned verw(unsigned sel); 

/* undocumented windows functions */ 

extern DWORD FAR PASCAL GetSelectorBase(unsigned sel); 

extern DWORD FAR PASCAL GetSelectorLimit ( unsigned sel); 

extern void FAR PASCAL SetSelectorBase(unsigned sel, DWORD base); 

extern void FAR PASCAL SetSelectorLimit ( unsigned sel, DWORD limit); 



Figure 6: This is the DPMI header file. 

terrupt function, INT 31h AX=0300h— 
one of the most important "translation ser- 
vices" provided by DPMI. 

Wait a minute, though. Simulate Real 
Mode Interrupt? Translation service? Why 
can't we call INT 21h AH=52h via the C 
intdosx() function? 

The problem is this: The Windows ver- 
sion of DEV.C is running in protected 
mode. INT 21h AH=52h is an MS-DOS 
function that runs in real mode. Since Win- 
dows is a DOS extender, one of its primary 
responsibilities is to provide INT 21 h func- 
tions in protected mode so that Windows 
apps can open files, allocate memory, 
change subdirectories, and so on, simply 
by making INT 21h calls. But INT 21h 
AH=52h is a special case. Since it's an 
••^documented function, you have no idea 

;ther or not Windows provides direct 
access to it in protected mode. 

That's why you must invoke this func- 
tion via the DPMI Simulate Real Mode In- 




terrupt function. As can be seen in the 
get_doslist() function in Figure 8, a pro- 
gram loads up an image of the 32-bit CPU 
registers in an RMODE_CALL structure 
and then calls dpmi_rmode_intr(). Using 
dpmi_rmode_intr() is much like using the 
int86() function in Microsoft C and other 
compilers. 

The point of this exercise is not simply 
to show how you make undocumented 
DOS calls from a Windows application. 
For all we know, INT 21h AH=52h may 
be supported in protected-mode Windows. 
Furthermore, a DOS extender can provide 
direct access to the undocumented DOS 
functions from protected mode. For exam- 
ple, Version 3.0 of Phar Lap's 386 DOS- 
Extender provides this and many other un- 
documented DOS functions in protected 
mode, so it eliminates the need for a Simu- 
late Real Mode Interrupt function. 

However, there will always be some 
functions to which a DOS extender does 



not provide direct access. The INT 21h 
AH=52h example is representative of that 
larger problem. If there is an interrupt- 
based service that you need to call and it is 
not supported directly in protected-mode 
Windows, then you must use INT 31h 
AX=0300h, probably via a C interface 
like dpmi_rmode_intr() as indicated 
above. DPMI also provides similar func- 
tions for calling stack-based real-mode 
procedures. 

ACCESSING REAL-MODE MEMORY 

The get_doslist() function returns a far 
pointer to the DOS ListOfLists structure. 
But what kind of far pointer? When writing 
protected-mode programs for a fundamen- 
tally real-mode operating system like 
DOS, you must accustom yourself to ask- 
ing, "Is this a real-mode pointer or a pro- 
tected-mode pointer?" In the case of 
get_doslist(), INT 21h AH=52h returns a 
real-mode pointer in ES:BX even if you in- 
voke it via the dpmi_jrmode_intr() func- 
tion. 

You now have a real-mode pointer, and 
you want to examine the corresponding 
block of memory in protected mode. Thus, 
the next important #ifdef WINDOWS 
block in DEV.C calls the map_real() func- 
tion. This function's job is to take a block 
of memory (whose size and real-mode ad- 
dress are passed as parameters) and return 
an equivalent protected-mode pointer. 

Any time you have a Windows program 
that needs to peek or poke a piece of real- 
mode memory, you can use the map_real() 
function in DPMI.H and DPMI.C (along 
with its complement, the free_ 
mapped_seg() function) without knowing 
anything about the underlying complex- 
ities of DPMI. Here, however, you may be 
interested in how map_real() works. 

INSIDE MAP_REAL() 

In DPMI.C, map_real() is built on top of 
the DosMapRealSegO function, which in 
turn is built on top of several low-level C 
interfaces to DPMI functions. 

The reason for all these layers is that the 
DPMI specification is extremely low lev- 
el. Recall that the intent of DPMI was to 
provide services for a handful of DOS ex- 
tender vendors to assure compatibility 
among their protected-mode extensions to 
MS-DOS. DPMI's developers had no idea 
that large numbers of Windows program- 
mers would need to call DPMI services di- 
rectly. Thus, it is best to construct several 
higher-level layers on top of DPMI. 

The actual DPMI functions (with their 
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DPMI . C -- DPMI functions, plus some undocumented Windows functions that 
provide the same functionality, plus several layers of "sugar coating" 
on top of these low- level services, to make them palatable 

Copyright (c) 1991 ziff Communications Co. 
PC Magazine * Andrew schulman 

*/ 

(include <windows.h> 
(include <dos.h> 
(include "dpoii -h" 

(define MAKEP(seg, ofs) ((void far *) HAKELONG ( <of s ) , (seg))) 

BOOL dpmi_present ( void j 
{ 

asm mov ax, 16S6h 
_asm int 2fh 
_asm not ax 

> 

void dpmi_versior.(unsigned «pmaj, unsigned "pmin, 
unsigned *pflags, unsigned *pproc) 

( 

unsigned char maj, min, proc; 
unsigned flags; 
_asm { 

mov ax, 9499b 

int 31h 

mov maj, ah 

mov min, al 

mov flags, bx 

mov proc, cl 

> 

•pmaj = ma 3; 
•pmin * min; 
•pflags = flags; 
•pproc = proc; 

> 

/• Performs a real-mode interrupt from protected mode »/ 
BOOL dpmi_rmode_intr(unsigned intno, unsigned flags, 
unsigned copywords, RMODE_CALL far *rmode_call) 

{ 

if (flags) intno |= 9x190; 
_asra { 

push di 

mov ax, 0300h // simulate real-mode interrupt 

mov bx, word ptr intno // interrupt number, flags 

mov cx, word ptr copywords // words to copy from pmode to rmode stack 

les di, dword ptr rmode_call // ES:DI = addr of rmode call struct 

int 31h // call DPMI 

jc error 

mov ax, 1 // return TRUE 

jmp short done 



> 

_asm xor ax, ax 
_asm pop di 



// return FALSE 



error : 
done : 

} 



/* Allocates a single protected-mode LDT 
unsigned dpmi_sel(void) 



_asm ( 

xor ax, ax 

mov cx, 1 

int 31h 

jc error 

jmp short done 

} 

r : 

asm xor ax, ax 



// Allocate LDT Descriptors 

// allocate ]uat one 

// call DPMI 

// AX holds new LDT selector 



// failed 



done : ; 
} 

BOOL dpmi_set_descriptor(unsigned pmodesel, DESCRIPTOR far »dj 

I 

push di 

mov ax, 000ch // Set Descriptor 

mov bx, word ptr pmodesel // protected mode selector 
les di, dword ptr d // descriptor 
int 31h // call DPMI 

jc error 

mov ax, 1 // return TRUE 

jmp short done 



ax // return FALSE 



} 

error: 

done; 

_asm pop di 

> 

BOOL dpmi_get_descriptor(unsigned pmodesel, DESCRIPTOR far *d) 

< 

_asm { 

push di 

mov ax, 00flbh // Get Descriptor 

mov bx, word ptr pmodesel // protected mode selector 



lee di, dword ptr d // descriptor 
int 31h // call DPMI 

jc error 

mov ax, 1 // return TRUE 

jmp short done 

> 



_asm xor ax, ax 
_asm pop di 



// return FALSE 



error : 
done : 
> 



BOOL dpmi_sel_free(unsigned pmodesel) 
{ 

_asm { 

mov ax, 9991h // Free LDT Descriptor 

mov bx, word ptr pmodesel // selector to free 

int 31h // call DPMI 

jc error 

mov ax, 1 // return TRUE 

jmp short done 



> 



asm xor ax. 



// return FALSE 



done : ; 
} 

f* Layer on top of DPMI and Windows services *««»»«»*»**»*•«»**•*••**•• 

unsigned DosAllocRealSeg(DWORD bytes, unsigned *ppara, unsigned *psel) 

DWORD dw = GlobalDosAlloc (bytes ) ; 
if (dw mm NULL) 

return 8; /* insufficient memory •/ 
•ppara = HIWORO(dw); 
•psel = LOWORD(dw); 
return 0; 



unsigned DosFreeRealSeg ( uns igned sel) 
{ 

return (GlobalDosFree ( sel ) 1= NULL); 



Use DPMI services to map a real-mode paragraph into protected-mode 
address space. First we get a selector using the DPMI "Allocate 
LDT Descriptors" call (INT 31h Function 9099b), via our dpmi_sel() 
function, we then get the descriptor for any old data segment in 
our program so that it can be used as a template of sorts for the 
new descriptor. This is done with the DPMI "Get Descriptor" call 
(INT 31h Function 0B0Bh), via our dpmi_get_descriptor( ) function, 
we then alter the descriptor to reflect the "rmpara" and "size- 
requested, and finally associate the descriptor with our LDT 
selector, using the DPMI "Set Descriptor" call (INT 31h Function 
000Ch). All the user needs, of course, is the selector itself. 

*/ 

unsigned DosMapRealSeg ( unsigned rmpara, DWORD size, unsigned far *psel) 
{ 

DESCRIPTOR d; 
unsigned long addr; 
unsigned sel = dpmi_sel(); 
if (i sel) 

return 8; /* insufficient memory */ 
/* make sure psel is valid */ 
if (! verw( FP_SEG(psel) ) ) 

return 490; /• invalid selector error */ 
/* get descriptor for any data segment */ 
dpmi_get_de script or ( FP_SEG ( psel ) , fid ) ; 
d. limit = (unsigned) size - 1; 
addr = ((unsigned long) rmpara) «. 4L; 
d.addr_lo = (unsigned) addr; 
d.addr_hi « (unsigned char) (addr » 16); 
d. reserved = d.addr xhi = 0; 
dpmi_set_descriptor ( sel , id) ; 
•psel = ael; 

return 0; /• success */ 



signed DosFreeSeg(unsigned sel) 



Use undocumented windows function to retrieve the real-mode 
equivalent to a protected mode pointer. Of course, we could also 
have used dpmi_get_descriptor ( ) here, but GetSelectorBase ( j 
is slightly more convenient. If the base of the selector is 
above the one-megabyte watershed, then there is no real-mode 
equivalent, so we return NULL. 

*/ 

void far *DosProtToReal (void far *prot) 
{ 

unsigned long base = GetSelectorBase ( FP_SEG (prot )) ,- 
if (base > 3xfffffl) 

return NULL; /* not accessible in real mode «7 

else 

return MAKEP ( base » 4, (base fi 0xBF) + FP_OFF(prot) ) ; 

} 

unsigned 9990H = 0; /* undocumented windows selector •/ 



Figure 7: The source code for DPMI.EXE. 
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unsigned mapped = 0; /* keep track of number of mapped selectors */ 

unsigned getjnapped(void) < return mapped; ) 

t* 

Map a real-mode pointer into our protected mode address space. 
If the real-mode pointer is in the first 64k of memory, use the 

undocumented windows selector 0000H. otherwise, use DPMI 

services via our DosMapRealseg ( ) function, which provides a more 
convenient layer on top of DPMI. This map_real() function in 
turn provides a more convenient layer on top of DosMapRealseg ( ) . 
Note that DosMapRealseg ( ) takes a paragraph address, whereas 
map_real takes a full segment :off set real-mode pointer. 

•/ 

void far "map_real < void far *rptr, unsigned long size) 
{ 

unsigned seg, ofs, sel; 

if (I 0000H) /* one time init: get undocumented windows selector «/ 

00H = LOWORD {GetProcAddress ( GetModuleHandle ( "KERNEL" ) , " 00 00H" ) ) ; 

seg ■ FP_SEG( rptr ) ; 
of 9 = FP_OFF( rpti) ; 

if ((seg < 0x1000) && ((ofs + size) < 0XFFFF ) ) 

return MAKEP ( 0000H, (seg « 4) + ofs); 

if (DosMapRealseglseg, size + ofs, (eel) 1* 0) 



return ; 
mapped++i 

return MAKEPfsel, ofs); 

> 

void free_mapped_seg(void far *fp) 
< 

unsigned sel = FP_SEG(fp); 
if (sel == 0000H) 

return; 
if (DosFreeseg(sel) == 0) 

mapped — ; 

> 

/« Use Intel VERW instruction to validate pointers */ 
unsigned verw(unsigned sel) 

( 

_asm mov ax, 1 
_asm verw sel 
_asm je short ok 
_asm xor ax, ax 

ok;; 
) 



C interfaces in DPMI.C) used when 
DEV.C calls map_real() are these: 

■ Allocate LDT Descriptors (INT 3 lh 
AX=0000h); dpmi_sel() 

■ Get Descriptor (TNT 3 lhAX=000Bh); 
dpmi_get_descriptor() 

■ Set Descriptor (INT 3 lh AX=000Ch); 
dpmi_seL_descriptor() 

LDT? Descriptor? It's hard to see what 
this has to do with accessing real-mode 
absolute memory locations from a protect- 
ed-mode program. In last issue's Lab 
Notes, however, you'll recall that in pro- 
tected mode, the XXXX portion of an 
XXXX-.YYYY pointer is called a selector, 
and that this selector is effectively an index 
into what is called a "descriptor table." 
This is in contrast to real mode, in which 
an XXXX-.YYYY pointer (1234:0005, for 
example) is merely a slightly warped rep- 
resentation of an absolute memory address 
like 12345h. 

Memory addressing in protected mode 
is indirect. Thus, the absolute memory ad- 
dress that corresponds to a protected-mode 
pointer of 1234:0005 depends entirely on 
the "base address" that is stored in the de- 
scriptor corresponding to selector 1234h. 
It bears no relation to the value of the selec- 
tor itself. In Windows 3.0, all Windows 
programs share a common table of such 
descriptors, called the Local Descriptor 
Table (LDT). All memory references from 
Windows programs essentially go through 
the LDT. 

This indirection is part of the mecha- 
sm that the Intel processors use to en- 
.ce protection. It is also why we can't 
peek at addresses such as 12345h simply 
by forming a pointer that looks like 
1234:0005 (or, more likely, peek at an ad- 



dress such as 046Ch simply by forming a 
pointer that looks like 0040:006C or 
0000:046C). In protected-mode Windows, 
selectors such as 1 234h and 0040h are sim- 
ply being used as indexes for table lookup 
in the LDT. (Technically, this is some- 
thing of an oversimplification of the won- 
derfully baroque mechanism actually used 
in the Intel processors. F6r the actual bit- 



In Windows 3.0, all 
Windows programs 
share a table of 
descriptors known as 
the Local Descriptor 
Table, and all memory 
references essentially 
pass through it. 



by-bit details, see Ray Duncan et al., Ex- 
tending DOS (Reading Mass.: Addison- 
Wesley, 1990, or Jeff Prosise, "Seg- 
mented Memory," PC Magazine, March 
26, 1991.)) 

Fortunately, however, the indirection 
does more than cause a problem for pro- 
tected-mode Windows applications; it also 
provides the solution to the problem. After 
all, if you want to examine address 46Ch, 
for example, you don't really care what the 



XXXX-.YYYY pointer looks like. If there 
were a protected-mode descriptor some- 
where whose base address was 400h, you 
could use a selector that corresponded to 
this descriptor, even if the selector value it- 
self bore no resemblance to the number 40, 
400, or whatever. And you could always 
save the selector in a variable called my40, 

bios_seg, or perhaps 0040H. 

In order to access absolute memory lo- 
cations in protected mode, then, what you 
need is to get a selector whose associated 
descriptor has a base address, limit, and 
access-rights that correspond to the abso- 
lute address you're interested in. And 
that's exactly the sort of service DPMI pro- 
vides. 

In the DPMI.C program, the DosMa- 
pRealSegO function first calls dpmi_sel() 
to allocate an LDT descriptor and return its 
corresponding selector. Next it calls 
dpmi_get_descriptor() to get a descriptor 
for any data segment in your program, to 
serve as a kind of "template" for the new 
descriptor. Then it alters the descriptor to 
reflect the base address and size requested 
(for example, sizeof(DeviceHeader) bytes 
starting at 106E:0000). Finally, you install 
this altered descriptor using the 
dpmi_set_descriptor() call. Presto! The se- 
lector now corresponds to a descriptor with 
the base-address and size that the caller re- 
quested. The only thing that the caller 
needs back is the selector, which the func- 
tion returns. 

As I mentioned earlier, you can use the 
map_real() function without understand- 
ing any of this explanation, but knowledge 
of how protected mode works and of how 
to use DPMI is going to be increasingly 
valuable. 
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A LIMITED RESOURCE 

Returning to the code for DEV.C (Figure 
8), note that the map_real() function is 
called in a loop as DEV walks the DOS de- 
vice chain. This loop — which is actually 
the central part of the program — has been 
excerpted for greater clarity in Figure 9, 
and can be contrasted with the real-mode 
code shown previously in Figure 2. Com- 
paring Figure 2 with Figure 9 will show 
you the major difference between the real- 
mode and protected-mode versions of the 
program. 

In addition to calling map_real() in the 



loop, the free_mapped_seg() function in 
DPMI.C is also called upon to free up 
mapped selectors. This is extremely im- 
portant, because descriptors and their cor- 
responding selectors are a precious limited 
resource. Remember, all Windows pro- 
grams (at least in Version 3.0) share a 
common LDT, and this can hold a maxi- 
mum of only 8, 192 descriptors. 

Freeing mapped selectors is so impor- 
tant that the map_real() and free_map- 
ped_seg() functions in DPMI.C keep track 
of how many outstanding mapped selec- 
tors there are. Just before DEV.C is ready 
to exit, it checks to make sure no mapped 
selectors have been left behind, for these 
are not automatically freed when a Win- 
dows program terminates. 



UNDOCUMENTED WINDOWS 

If you recall its original purpose, the DF 
program needs to print out not only the 
name of each DOS device driver, but also 
its address. Although DEV in Windows 
uses a protected-mode address returned 
from the map_real() function, this is not 
the address you want printed to the dis- 
play. The protected-mode address is an ar- 
bitrary value that bears no relation at all to 
the real-mode address that would make 
sense to the DEV program user. 

Thus, you want to display the real- 
mode address that corresponds to the pro- 
tected-mode address. Since this real-mode 
address is whatever value was passed into 
map_real() in the first place, you could, of 
course, have saved it away somewhere for 



DEV.C — display MS-DOS device chain 

Copyright (c) 1991 Ziff Communications Co. 
PC Magazine * Andrew Schulman 

real mode: 

Borland C++ 2.0: bcc dev.c 
Microsolt C 6.8: cl dev.c 

Borland C++ 2.0 (DPMI.C -must* be compiled with -B flag): 
bcc -w -DWINDOHS -2 -B dev.c printf.c dprai.c 
rc dev.exe 

Microsoft C 6.0: 

cl -c -AS -G2sw -Oais -Zpe -W3 -DWINDOWS dev.c printf.c dpmi.c 
link /align; 16 dev dpmi printf , dev, , /nod alibcew libw,win.def 
rc dev . exe 

WIN.DEF: 

; WIN.DEP -- generic windows .def file 

EXETYPE WINDOWS 

STUB 'WINSTUB.EXE' 

CODE PRELOAD MOVEABLE DISCARDABLE 

DATA PRELOAD MOVEABLE MULTIPLE 

HEAPSIZE 10240 

STACKSIZE 5120 



•include <atdlib.h> 
•include <stdio.h> 
•include <string.h> 
•include <dos.h> 
llfdef WINDOWS 
•include <windows.h> 
•include "dpmi.h" 
•include "printf. h" 
•endif 

•ifdef WINDOWS 

char *app = "Walk DOS Device Chain-; 

•define pytc(s) Mess age Box ( NULL, s, app, MB OK) 

•endif 

•define fail(s) return puts(s) 



ofs) \ 

(((unsigned long) (Beg) << 16) 



•ifndef MK_FP 
•define MX_FP(seg, 
{{void far *) 
•endif 



/• some device attribute bits •/ 
•define CHAR_DEV (1 « 15) 
•define INT29 (1 « 4) 

•define is_CLOCK (1 « 3) 
•define IS_NUL (1 « 2) 

•pragma pack( 1) 

typedef struct DeviceDriver { 

struct DeviceDriver far "next; 
unsigned attr; 
unsigned strategy; 
unsigned intr; 
union { 

unsigned char name[8]; 
signed char blk_cnt; 



> 

> DeviceDriver; 



typedef struct { 







0, 0, *r)) ? MX_FP(r.ea, r.ebx) 



unsigned char mi3c[8]; 
DeviceDriver far *clock ; 
DeviceDriver far *con; 
unsigned char misc2(lB]; 
DeviceDriver nul; /* not a pointer */ 
// . . . 

} ListOfLists; // DOS 3.1+ 

ListOfLists far *get_doelist(void) 
{ 

•ifdef WINDOWS 

h 

call undocumented DOS INT 21h Function 52h via DPMI "Simulate 
Real Mode Interrupt" call (INT 31h AX-0300h), and return 
the resulting real-mode pointer 

»/ 

RMO D E_C ALL r; 

memset(fir, 0, sizeof(r>); 

r.eax = 0x5200; 

return (dpmi_rmode_int r ( 0x2 1, 
• else 

union REGS r; 

Struct SREGS s; 

segread( is ) ; 

s.es - r.x.bx - 0; 

r.h.ah = 0x52; 

intdosx(tr, fcr, As); 

return MK_FP(s.es, r.x.bx); 
•endif 

1'^}; ' ■ « p- 

I ifdef WINDOWS 

int PASCAL HinHain ( HANDLE hlnstance, HANDLE hPrevInatance, 

LPSTR IpszCmdLine, int nCmdShow) 
•else 

int main(int argc, char *argv[ ] ) 

lendif 

( 

ListOfLists far "dosiiat; 

DeviceDriver far *dd; 
•ifdef WINDOWS : 

DeviceDriver far *next; 

int mapped; 
•endif 

•ifdef WINDOWS 

if (l (GetwinFlags{ ) L WF_PMODE ) ) 

failfThis program requires windows Standard or Enhanced mode"); 

if (I dpmi _present ( ) ) 

fail ("This program requires DPMI INT 31h services"); 

lendif 

if (i (doslist = get_doslist( ) ) ) 

fail("INT 21h Function 52h not supported"); 

•ifdef windows 

/• get protected-mode pointer to Dos internal variable table */ 
doslist = ntap_real (doslist, sizeof ( ListOfLists )) ; 

open_display(app) ; 
•endif 

/* This block of code double-checks that everything is ok */ 

/* NUL is part of DOSLIST, not a pointer, bo don't need to map */ 

if {_fmemcmp{dosliat->nul.u.name, "NUL ", 8) 1= 0) 

fail(-NUL name wrong'); 
if (! (doslist->nul.attr s IS_NUL) > 

fail{ *NUL attr wrong-); 



■ 



Figure 8: Walking the device chain in protected-mode Windows is achieved by DEV.C. 



PC MAGAZINE JUNE 25, 1991 



T ab Notes 



•lfdef WINDOWS 

/• CON is pointer, so need to map •/ 

dd " map_real (doslist->con, aizeof (DeviceDriver) ) ; 

• else 

dd = doslist->con; 
•end if 

if ( fmemcrap(dd->u.nanie, "CON " , 8) 1= 0) 

7ail("CON name wrong" ) ; 
if (1 <dd->attr t. CHAR_DEV) ) 
fail("CON attr wrong"); 
iifdef WINDOWS 

f ree_mapped_seg ( dd ) ; 
lendif 

•lfdef windows 

/* CLOCKS is also pointer, so need to map */ 

dd = map_real(dofilist->clock, aizeof (DeviceDriver) ) ; 

• else 

dd - doslist->clocx; 
lendif 

if ( fT.emcmp(dd->u.narae, "CLOCKS 

Tail< "CLOCKS name wrong"); 
if U idd->attr & IS_CLOCK)) 
fail("CLOCK$ attr wrong"); 
•afdef windows 

f ree_mapped_seg(dd) ; 
lendif 

/* print out device chain */ 
dd ■ idoslist->nul; 
iifdef windows 
*or <;;) 
{ 



8) I- 0) 







printf(*%Pp *, DosProtToReal(dd) ) ; /• print real-mode addr */ 
if (dd->attr i. CKAR DEV) 

printf ( *%.8Fa\r\'n- , dd->u . name ) ; 

else 

printf { "Block dev: %u unit ( s)\r\n" , dd->u.bltc cnt); 
next - dd->next; /• get next pointer *7 

/* first time through, this will free selector to doslist */ 
f ree_mapped_seg(dd) ; /• THEN free rmode seg */ 

if (FP_OFF(next ) == -1) /• is there a next7 "/ 

break; 

dd = map_real(next, si2eof (DeviceDriver )) ; /* map it •/ 
Yield();~ /• no message loop in this program, so yield */ 

) 

•else 

do ( 

printf ("%Fp\t", dd); 

if (dd->attr t CHAR_DEV) 

printf ( •% .8Fs\n" , dd->u .name) ; 

else 

printf ("Block dev: unit(s)\n", dd->u .blk_cnt ) ; 
dd » dd->next; 
} while (FP_OFF(dd->next) ! = -1); 
•endif 

•lfdef WINDOWS 

if (mapped = get_mapped( ) ) 

printf(-tu remaining mapped selectors 1 \r\n" , mapped); 
show_display( ) ; 

return mapped; /• indicates success */ 
*else 

return 0; 
•endif 
) 



PARTIAL LISTING 



ListOfLists far *doslist; 
DeviceDriver far *dd; 
// ... 

dd = &doslist->nu 1 ; 

'or (;;) 

i 

printf ("%Fp " ( DosProtToReal (dd) ) ; /• print real-mode addr */ 
if (dd->attr i CHAR DEV ) 

printf ( "%.8Fs\r\n- , dd->u.name) ; 

else 

printf ( -Block dev: %u unit ( s ) \r\n- , dd->u.blk cnt); 
next = dd->next; /* get next pointer '7 

/* first time through, this will free selector to doBlist */ 
free_mapped_seg(dd) ; /* THEN free rmode seg */ 

if (FP_OFF(next) == -1) /* is there a next7 */ 

break; /* if not, we're done */ 

dd = map_real(next, sizeof (DeviceDriver) ) ; /* map it */ 
Yield(); /« no message loop in this program, so yield */ 



Figure 9: The loop within DE V.C that walks the device chain. For an idea of the differences between 
real- and protected-mode, compare this to Figure 2. 



later use before calling map_real(). 

Instead, however, DEV.C calls the 
DosProtToReal() function that was imple- 
mented in DPMI.C. Given a protected- 
mode pointer, this function attempts to re- 
turn the corresponding real-mode pointer. 
The word "attempts" is important here, 
because if the base address for the protect- 
ed-mode pointer is above the 1MB Magi- 
not Line, then the protected-mode pointer 
has no real-mode counterpart. 

In any case, DosProtToReal() attempts 
make the conversion. Just for variety, 
ner than calling the dpmi_get_descrip- 
tor() function, it calls an undocumented 
Windows function, GetSelectorBase(). If 
the base address of the selector is greater 



than FFFFFh, then the pointer cannot be 
converted. Otherwise, DosProtToReal() 
combines the selector's base address with 
the protected-mode pointer's offset to 
form the desired real-mode pointer. 

The GetSelectorBaseQ function used 
here is one of several such undocumented 
Windows functions. The function proto- 
types for several others are shown in 
DPMI.H (Figure 6). In fact, I could have 
used the SetSelectorBaseQ and SetSelec- 
torLimit() functions, together with the do- 
cumented Windows function AllocSelec- 
tor(), and avoided DPMI entirely. 

With regard to using undocumented 
functions, it's well to remember that there 
is no guarantee that they will continue to be 



supported in future releases of Win- 
dows — or even that they work 100 percent 
of the time in this release. That may be 
why they're undocumented in the first 
place! 

On the other hand, these undocumented 
Windows functions really are far more con- 
venient than the raw DPMI interrupt 31h 
functions. Further, in my experience, they 
have always worked — or at least worked 
as well as anything else in Windows 3.0. 
The tiny UNDOCSEL.C program listed in 
Figure 10 shows how these functions 
would be used to print out the BIOS timer- 
tick count at absolute memory location 
46Ch (real-mode pointer 0040:006C). 

Map_real() also makes use of an undoc- 
umented Windows feature: the 0000H 

selector. This is a hard-wired selector 
maintained by Windows that maps the 64K 
block of memory beginning at absolute 
memory location zero. Since many of the 
DOS device headers will be located in this 
first 64K of memory, it just made sense to 
use the Windows selector in this case. 

Microsoft's Windows Guide to Pro- 
gramming (Chapter 16, "More Memory 
Management") describes global selectors 
such as _B000H and _B800H. These 
are used by full-screen Windows applica- 
tions that do direct screen writes, such as 
Turbo Debugger for Windows (TDW) and 
the new single-screen version of Code- 
View for Windows (CVW). Note, howev- 
er, that the Microsoft documentation does 

not mention the extremely useful 0000H 

selector. 
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UNDOCSELC COMPLETE LISTlING 



f* 

UNDOCSEL.C -- illustrates undocumented Windows selector functions 
cl -c -AS -G2sw -Oais -Zpe undocsel.c printf.c 

link /align:16 undocsel printf , undocsel, , /nod slibcew libw,win.def 
rc undocsel.exe 

Copyright (c) 1991 Ziff Communications Co. 
PC Magazine * Andrew schulman 

*/ 

•include <windows.h> 
♦include <dos.h> 
((include "printf. h" 

/* undocumented Windows functions */ 

extern DWORD FAR PASCAL GetSelectorBase( unsigned sel); 
extern DWORD FAR PASCAL GetSelectorLimit(unsigned sel); 
extern void FAR PASCAL SetSelectorBase ( unsigned sel, DWORD base); 
extern void FAR PASCAL SetSelectorLimit ( unsigned sel, DWORD limit); 

((define FAIL(s) return Mess age Box ( NULL, s, -UNDOCSEL", MB_OK), 

int PASCAL WinMain ( HANDLE hlnstance, HANDLE hprevlnstance, 
LPSTR lpszCmdLine, int nCmdShow) 

{ 

unsigned sel, ds ; 
unsigned long Tar *pticks; 
if (I (GetwinFlags( ) t WF_PMODE)) 

FAIL( "This program requires WindowB Standard or Enhanced mode"); 
open_display( "Undocumented Selector Function Test"); 
_asm mov _ds, ds 

sel = AllocSelector(_ds ) ; // copy DS 

printf ( "sel=%04X\n" , sel); 

SetSelectorBase(sel, 0x400); // BIOS data area 
SetSelectorLimit (sel, 0XFFFF ) ; // only 64k allowed 
FP_SEG(pticks) - sel; 

FP OFF(pticks) = 0x6c; // BIOS timer tick 

printf ("base=%081x limit=%081x ticks=S081X\n" , 

GetSelectorBase(sel) , CetSelectorLimit ( sel ) , *pticks); 
showdisplay ( ) ; 
FreeSelector ( sel) ; 

> 



Figure 10: The source code, UNDOCSEL.C, that uses an undocumented Windows function to print 
out the BIOS timer-tick count. 



According to the Microsoft documenta- 
tion, these global selectors are usable only 
from an assembly language program. The 
code in map_real() shows one way that 
0000H can be accessed from a C pro- 
gram, however, and the other global selec- 
tors can be accessed in a similar fashion. 
One note of caution is in order: There is an- 
other undocumented selector, 0040H, 

which you would think mapped the BIOS 
data area at address 400h. In fact, this se- 
lector maps only the 2FFh bytes at address 
0. Another undocumented selector, 

ROMBIOS, is merely an alias for 

_F000H. 

WINDOWS AND DPMI 

Having now seen how to call DPMI from 
Windows programs and how Windows 
provides its own undocumented layer on 
top of DPMI , it is natural to ask how DPMI 
fits into the Windows API. 



GlobalDOSAIIoc() will 




be very important for 




Windows developers 




who need access to 




conventional memory. 





You won't see DPMI mentioned in Mi- 
crosoft's Windows documentation. In fact 
the Microsoft documentation barely refers 
to protected mode or to the fact that Win- 
dows in Standard and 386 Enhanced 
modes is a DOS extender. For many years, 
Windows essentially/a£«af protected mode 
in software and even required developers 



to do a lot of work to help maintain the fic- 
tion. Now that Windows programs rea' 
do run in protected mode, most of the 
memory-management nonsense formerly 
required of Windows programs has disap- 
peared. However, Microsoft's documen- 
tation barely mentions this either, and it 
downplays the massive change wrought by 
Windows 3.0 under the diplomatic title, 
' 'improved memory management. ' ' 

Microsoft's only explicit mention of 
DPMI is a brief five-page document titled 
"Windows INT 21H and NetBIOS Sup- 
port for DPMI," which is included in a 
packet of Microsoft Windows develop- 
ment notes (Part No. 050-030-313). 

According to this rather obscure docu- 
ment, only a handful of DPMI functions 
should be used from Windows programs. 
The supported functions (which are listed 
on page 390 of PC Magazine's February 
26, 1991, issue) are those that set and get 
real-mode interrupt vectors, generate real- 
mode software interrupts, and call real- 
mode code. 

For example, INT 31h AX = 0300h 
(Simulate Real Mode Interrupt), together 
with the Windows function GlobalDosAl- 
loc(), can be used for generating software 
interrupts not supported in protect 
mode. We will see an example of this to- 
ward the end of this article, in the short 
program TRUENAME.C. 

According to Microsoft, apart from 
those listed, no other DPMI functions "are 
required for Windows applications, since 
the Kernel provides functions for allocat- 
ing memory, manipulating descriptors, 
and locking memory. ' ' 

Unfortunately, many developers have 
found that the Windows Kernel, even com- 
bined with the few "supported" DPMI 
functions, does not in fact provide every- 
thing they need to talk to real-mode TSRs, 
network drivers, and the like. 

Again, the problem is this: Given a 
block of memory at an absolute real-mode 
address (such as the BIOS data area or the 
DOS device chain), how do you access 
this memory from your protected-mode 
Windows program? Even with the undocu- 
mented 0000H selector and the docu- 
mented selectors such as AOOOH, there 

is still an inaccessible hole between 
lOOOOhandAOOOOh! 

The choice is either to use the undocu- 
mented SetSelectorBase() and SetSelef 
torLimitO functions, as in UNDOCSEL 
(Figure 10), or to use DPMI directly. The 
ability to map an arbitrary real-mode ad- 
dress into a program's protected-mode ad- 
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he first problem you face when port- 
ing a PC program to Microsoft Win- 
dows is that you can't use such familiar 
output functions as printfQ in C or 
Write() in Turbo Pascal. Instead, you 
must employ Windows functions like 
TextOut() or DrawText(). And, of 
course, you must completely restruc- 
ture the program so that it responds to 
Windows "events." 

Of course? The familiar claim that 
"it takes 100 lines even to say 'hello 
world' in Windows," is often repeated 



PRINTF.H COMPLETE LISTING 



/* PRINTF.H */ 

BOOL open_display(char *appname) 
BOOL show_display (void) ; 
int printf (const char *fmt, ...).-. 
BOOL notepad(char far *s); 




The header file for the Windows 
ion of printfQ. 



even by die-hard Windows evangelists. 
(The latter may indeed see such com- 
plexity as a virtue!) This gives the mis- 
taken impression that even the smallest 
one-liner must be restructured as a lull- 
blown Windows program, complete 
with a WndProc message handler and 
calls to the RegisterClass() and 
CreateWindowO functions. 

Such a misconception makes it ex- 
tremely difficult for newcomers to get 
started in Windows programming, and 
it inhibits experienced developers from 
trying to write tiny utilities or throw- 
away experiments. 

It is true that if you use Microsoft C 
or Borland C++, you'll find that all 
the standard inputfoutput (stdio) func- 
tions, such as printfO, puts(), and 
gets(), have been yanked from the Win- 
dows libraries. Trying to call one of 
these functions from a Windows pro- 
gram causes the linker to generate an 
' 'unresolved external . ' ' 

But there is nothing magical about 



printf() or any other stdio function; 
stdio libraries can be built on top of the 
Windows API. For example, using Bor- 
land's Turbo Pascal for Windows 
(TPW), if you simply change the Pascal 
statement "Uses Crt" in a program to 
"Uses WinCrt," you've essentially 
created an instant Windows application: 
all your calls to the Pascal Write() state- 
ment go to a Windows window. Obvi- 
ously, the same thing can be done in C 
or C + + . In fact one wonders why Bor- 
land hasn't done it. In any case, it's rel- 
atively easy to write a module that al- 
lows its users to bring up Windows 
applications without rubbing their 
noses in the Windows API. 

As we saw in last issue's Lab Notes, 
the Windows MessageBoxO function 
can produce an entire screen of output. 
This makes it handy for tiny utilities 
like DEV. Alternatively, you can take 
advantage of Windows' multitasking 
and interprocess messaging to use an- 
other program (such as Notepad) as 



PRINTF. c simple output for small windows programs, 
using MessageBoxO or WinExec ( ) /SendHessage( ) 
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♦include <stdlib-h> 
tinclude <stdarg.h> 
tinclude <string.h> 
linclude <windows.h> 
tinclude "printf .h" 

•define BUF_SIZE 1024 

static char *str, "app; 
static unsigned cap, len; 
static int lines; 

BOOL open_display(char *appname) 
{ 

app = appname; 
cap = 128; 

if (t (str - malloc(cap) ) ) 

return FALSE; 
•str "= lines = len = 0; 
return TRUE; 



/* Maximum number of lines that HessageBox will hold 

static int max_ lines (void ) 

{ 

TEXTMETRIC tin; 

HWND hWnd * GetActiveWmdowf ) ; 
HOC hDC ■ GetWindowDC(hWnd) ; 
if (hDC == NULL) 



return 0; 
GetTextMetrics(hDC, Atm) ; 
Re leaseDC < hwnd , hDC ) ; 

return ( GetSystemMetr ic 9 ( SM_CY FULLSCREEN ) / 

(tm. tmHeight + tm . tmExter na 1 Leading ) ) - 5; 



BOol show_display(void) 

( 

if (lines <= max_lines()j 

HessageBox ( NULL, str , app, MB_OK) ; 

else 

notepad (str) ; 
free (str) ; 
return TRUE; 

) 

static BOOL append(Char *s2) 

{ 

char *s3; 

if (((len +=■ strlen(s2|) < cap) n strcat(str, a2)) 

return true; 
cap = len + 128; 
if (I (s3 = malloc(cap) ) ) 

return FALSE; 
strcpy (s3, str) ; 
Strcat ( s3 , s2 ) ; 
free( atr) ; 
str = s3; 
return TRUE; 

J 

int nlines(char *s2) 

( 

int c, n = 0; 
while (c = *s2++) 
if (c -\ n » ) 
n+ + ; 
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} 

int printf (const char "int, ...) 
( 

static chax s2 ( BUF_SIZE1 ; 

int len; 

va_list marker; 

va star t (marker , £ Bit) ; 

len = vsprintf ( 92, fmt, marker); 

lines += nlines(a2); 

va_end { marker ) ; 

append ( s2 ) ; 

return len; 

) 

BOOL notepad (char far *s) 
< 

HWND notepad; 
HWND edit_ctrl; 

if (WinExec( "notepad.exe", sw SHOWNORMAL) < 32) 
return FALSE; 



notepad = Findwindow(NULL, "Notepad - (untitled)"); 
edit Ctrl = GetFocus u ; 

sendMessagefnotepad, WM_S ETT EXT, 0, (char far *) app); 
sendHessage(edit_ctrl, WM_SETTEXT, 9, (char far *) s); 
return TRUE; 



»ifdef TESTING 

int PASCAL HinMain( HANDLE hinstance, HANDLE hPrevInstance, 
LPSTR IpszCmdI-ine, int nCmdshow) 

{ 

int i; 

open_di splay ( "GetSystemHe tries" ) ; 

for (i=0; i<37; i++) 

( 

printf ( "%d\t%d\r\n" , i , GetsystemMetrics ( i ) ) ; 
Yield( ) j 



show_display ( ) ; 



your ' 'display engine . ' ' Functions such 
as printfO can then be written on top of, 
and in terms of, such lower-level capa- 
bilities. 

DEV.C, listed in Figure 8 of the 
main article, looks a lot simpler than 
most Windows source code. It doesn't 
register a class, call CreateWindow(), 
or handle messages. Instead, it calls 
printf(). When compiling for Windows, 
however, it uses the new version of 
printfO supplied by PRINTF. H and 
PRINTF.C, listed in Figures A and B. 
Here, printf() simply accumulates text 
until a call to show_display(). The 
show_display() function uses the Win- 
dows MessageBoxO function. 

If there is more text than Message- 
BoxO can handle, then PRINTF.C uses 
WinExec() to fire up a copy of Notepad 
■^■^■^^^^^^^ 

dress space was left out of the published 
API, making DPMI even more necessary 
for Windows developers than Microsoft's 
brief description would indicate. 

USING GLOBALDOSALLOC () 

One documented Windows function that 
will be quite important for many develop- 
ers who need to access conventional mem- 
ory or call real-mode TSRs and drivers is 
GlobalDosAlloc(). This function allocates 
a block of conventional memory, returning 
both a real-mode paragraph address and a 
protected-mode selector to the memory. 

Suppose, for example, that you're writ- 
ing a piece of network software for Win- 
dows using a specification like NetBIOS or 
Novell IPX/SPX. In addition to needing 
dpmi_rmode_intr() (or its underlying 



and sends the text to Notepad using the 
WM_SETTEXT message and the 
SendMessage() function. The ability of 
one program to send text to another 
shows, incidentally, that Windows is 
genuinely message-based: "mes- 
sages" are a true form of interprocess 
communication, not just an elaborate 
way of describing a function call. 

Windows itself can sometimes help 
in the task of providing a Windows- 
based printf() . The Windows dynamic- 
link library USER. EXE provides the 
functions wsprintf() and wvsprintfO. 
Like the vsprintfQ of ANSI C, the 
wvsprintfO function can be used to con- 
struct other functions — such as 
printf() — -that take a variable number of 
arguments. Because wvsprintfO resides 
in a DLL, using this Windows version 



DPMI Simulate Real Mode Interrupt call, 
INT 31h AX=0300h) to generate the real- 
mode software interrupt, you must also 
pay attention to any buffers expected by 
the network driver. 

The NetBIOS INT 5Ch interface, for 
instance, expects a pointer to a Network 
Control Block (NCB) in ES:BX. When 
calling this from protected mode, even 
though you are going through the DPMI 
Simulate Real Mode Interrupt call, you 
must ensure ( 1 ) that the NCB is in conven- 
tional memory and (2) that ES:BX has a 
real-mode pointer. On the other hand, your 
program must manipulate the same NCB 
using a protected-mode pointer. 

That's where GlobalDosAlloc() comes 
in. By allocating out of conventional mem- 
ory and giving back both a real-mode para- 



of the function can reduce the size of 
your executable. 

Unfortunately, wvsprintfO does not 
support several useful "masks," such 
as %Fp. It is also sometimes awkward 
to use: Since it resides in a DLL, it ex- 
pects all strings to be passed as far 
pointers. In PRINTF.C, therefore, I 
ended up using the non-Windows 
vsprintfO function. 

In porting DEV.C to Windows, in 
any case, you can simply assume that 
you have a function called printfO that 
takes the same parameters and returns 
the same value (almost always ig- 
nored!) as the "regular" printfO, but 
that somehow "does the right thing" in 
displaying output under Windows. 
Thus, it really is possible to write sim- 
ple Windows programs! ■ 

graph address and a protected-mode selec- 
tor, it's exactly the function you need to 
use in conjunction with dpmi_ 
rmode_intr()- 1 found the way that Global- 
DosAllocO returns these two different val- 
ues annoying, so I constructed another 
function on top of it, DosAllocRealSeg(). 
(Like the earlier DosMapRealSegO, the 
name comes from the Phar Lap API. ) 

The GlobalDosAllocO function (imple- 
mented via the more convenient Dos- 
AllocRealSegO) and dpmi_rmode_intr(), 
are used in TRUENAME.C (Figure 11), 
the last tiny Windows program presented 
here. Because many readers don't ha' 
NetBIOS, I have again used an undo*, 
mented DOS call — the one category I 
know is available on every DOS machine, 
yet which is not supported direcdy from 
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TRUENAME.C 



COMPLETE LISTING 



< Me b sage Box ( NULL , 8, "TRUENAME" , HB_OK); exit(l); > 



/* truename.c */ 

linclude <windows.h> 
linclude <8tdlib.h> 
# include <ctype.h> 
linclude "printf.h" 
linclude "dpmi.h" 

Idefine fail(s) 

•define MAKEP(seg, ofs) ((void far *) MAKELONG ( ( of s ) , (Beg))) 

char far *truename(char far *s, char far *d) 

< 

RMODE_CALL r; 
unsigned para, sel; 
char far *b2; 

/* INT 21h AH=60h doesn't like leading or trailing blanks •/ 
while ( isspace( *s ) ) s++; 
s2 = s; 

while (*s2) b2++; 
s2 — ; 

while ( isspace( *s2 ) ) *s2 — = 0; 

if (DoBAllocRealSeg(256, ipara, tsel) 1= ) 

fail( "Couldn't allocate real-mode memory"); 
memset(4r, 0, aizeof(r)); 
r.eax - 0x6000; 
r.d8 ■ r.es = para; 
r.esi » 0; 
r.edi - 128; 

lstrcpy(MAKEP( eel, 0), s); 

if (i dpmi_rmode intr(0x21, 0, 0, &r)) 

faircDPMI real-mode intr failed"); 
latrcpy(d, (r. flags 4 1)? -<Invalid>" : (char far •) MAKEP(sel, 128)); 
if (DosFreeRealSeg(8el) != 0) 

fail("Couldn't free real-mode memory); 

return d; 

) 

it PASCAL WinMain( HANDLE hlnstance, HANDLE hPrevmstance, 
LPSTR IpszcmdLine, int nCmdshow) 

char buf[128]; 

if (l (GetwinFlags( ) i WF_PMODE) ) 

fail{"This program requires windowB standard or Enhanced mode"); 
if (I (IpszcmdLine it *lpszcmdLine ) ) 

fail( "syntax: truename <pathname>" ) ; 
sprintf(buf, "TRUENAME »Fs", IpszcmdLine); 
open_display(buf ) ; 

printf ( ■ %Fs\n" , truename ( IpszcmdLine, buf)); 
show_display( ) ; 



Figure 1 1 : TRUENAME.C shows how to pass a conventional memory buffer to a real-mode interrupt. 



protected-mode Windows. 

The TRUENAME program takes a 
pathname from the command line (for ex- 
ample, the Program Manager Run . . . 
command) and uses INT 21h AH=60h to 
return the "true" underlying pathname, 
with any DOS ASSIGNS, SUBSTs, 
JOINs, or network mappings resolved. On 
my machine at work, for example, drive F: 
is actually located on a Sun SPARCsta- 
tion, and running TRUENAME F: dis- 
plays something like 

\\EXPORT\DOS\A_ANDREH. 

The reason this program is a good illus- 
'-•nion of using GlobalDosAllocO together 

h dpmi_rmodeJntr(), is that INT 21h 
AH=60h expects a source pathname in 
DS:SI (such as "F:."), and a pointer to a 
128-byte destination buffer in ES:DI (into 



which it will place a string such as " WEX- 
PORT\DOS\A_ANDREW" ) . Before 
calling INT 21h AH=60h, the program 
must allocate a conventional-memory 
transfer buffer, copy the source string into 
it, put its real-mode address in DS:SI, and 
put the address of another conventional- 
memory transfer buffer (the destination) in 
ES:DI. When dpmi_rmode_intr() returns 
after INT 21h AH=60h has been invoked, 
you can copy the results out of the conven- 
tional-memory buffer. Of course, you 
must do this copying using the protected- 
mode pointer to the buffer. 

A GOOD PROBLEM 

There are many ways that Windows pro- 
grams can use DPMI. Other DPMI ser- 
vices I haven't discussed here let programs 
hook real-mode interrupt vectors, enhance 
debugging with access to protected-mode 



data structures such as the Global Descrip- 
tor Table (GDT), and catch GP faults and 
other exceptions. 

This last-mentioned possibility is really 
quite interesting. I earlier talked about the 
GP fault and UAE as if they were an im- 
mutable fact of protected-mode life. In 
fact, however, the GP fault is nothing but 
an interrupt ODh. DPMI makes a distinc- 
tion between interrupts and processor ex- 
ceptions and provides functions for han- 
dling exceptions like the GP fault. 

The DPMI Set Processor Exception 
Handler Vector (INT 31h AX=0203h) 
and the Get Processor Exception Handler 
Vector (INT 3 lh AX=0202h) calls can be 
used to replace Windows' annoying UAE 
with your own GP fault handler. Such a 
handler might display a message box po- 
litely asking the end user of a program that 
has GP faulted to call tech support, for ex- 
ample. Anything would be better than hit- 
ting the user with the "Unrecoverable Ap- 
plication Error" message! 

Amidst all the complexities of protect- 
ed-mode Windows, it's a good idea to con- 
clude by remembering the tremendous ad- 
vantages brought about by the demolition 
of the 1 MB " Berlin Wall . ' ' These far out- 
weigh any disadvantages resulting from 
the sudden inability to examine address 
400h with the pointer 0000:0400, for ex- 
ample. In any case, this discussion has 
shown that you can still examine the mem- 
ory at 400h; it's just that you can't do it 
with the pointer 0000:0400 or 0040:0000. 
Instead, you have to use whatever equiva- 
lent protected-mode pointer is returned 
from map_real(), from the underlying 
DPMI calls, or from a combination of un- 
documented Windows calls. 

The problem with low-level access 
from protected mode reflects PC program- 
ming's move to a new, higher level. We 
have broken the 640K barrier, but we have 
not shed our massive investment in DOS 
software. The programming problems 
demonstrated in this and the previous Lab 
Notes represent the successful compro- 
mise between protected mode and DOS. 
More and more programs are running in 
protected mode, yet the industry's invest- 
ment in DOS has been preserved. This is a 
good problem to have ! ■ 

Andrew Schulman is an engineer and writ- 
er at Phar Lap Software, in Cambridge , 
Massachusetts . Editor of the recent book 
Undocumented DOS, he is also a contrib- 
utor to Extending DOS, edited by Ray 
Duncan. 
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